Skip to main content

Email Blast Round‑Trip

This guide shows a complete round‑trip to launch an email “blast” using ValkyrAI’s Workflow Engine.

What you get:

  • Recipient selection with preference filtering
  • Template fetch/injection and merge with per‑recipient data
  • Async send queue to Mailtrap (dry‑run or live)
  • Simple stats, retries and event logging
  • A passing integration test to validate the flow

Modules used

  • emailRecipientsModule: Reads recipients from moduleData and exposes them as recipients in the map.
  • preferenceFilterModule: Filters recipients by optIn/marketingOptIn and acceptedTos.
  • contentTemplateFetchModule: Fetches ContentData by id and outputs template and subject (optional; you can also use mapInjectModule).
  • mapInjectModule: Injects arbitrary JSON keys into the map (useful for tests or inline templates/subjects).
  • templateMergeModule: Applies a Mustache‑style merge of {{key}} placeholders for each recipient. Outputs mailItems.
  • mailtrapSendModule: Sends mailItems to Mailtrap with concurrency, retry and dryRun support. Outputs sendStats and failures.

Environment variables

Example workflow (conceptual)

  1. EmailRecipientsModule
    • moduleData: { "recipients": [{"email":"user@example.com","firstName":"Sam","optIn":true}] }
  2. PreferenceFilterModule
    • moduleData: { "defaultOptIn": false }
  3. ContentTemplateFetchModule or MapInjectModule
    • MapInject example: { "template": "Hi {{firstName}}", "subject": "Hello {{firstName}}" }
  4. TemplateMergeModule
    • moduleData: { "format": "text", "defaultSubject": "Hello" }
  5. MailtrapSendModule
    • moduleData: { "dryRun": true, "concurrency": 4, "fromEmail": "no-reply@valkyrlabs.com" }

Integration test

  • See valkyrai/src/test/java/com/valkyrlabs/workflow/EmailBlastWorkflowIT.java.
  • The test composes a one‑task workflow with the modules above, runs them sequentially (engine‑lite) and asserts sendStats:
    • attempted = 1, succeeded = 1, failed = 0

Notes

  • To run live against Mailtrap, set the environment variables and remove dryRun or set it to false.
  • For full engine execution with Quartz scheduling, register the workflow via the Workflow API and start it per your schedule.
  • Event logging uses EventLogRepository when available; test uses dry‑run and asserts in‑memory sendStats to avoid DB setup.